29 sierpnia 2025Polski

Opanuj hak useFormStatus w React do płynnej obsługi przesyłania formularzy, śledzenia postępów i poprawy UX. Naucz się tworzyć solidne, przyjazne formularze.

React useFormStatus: Kompleksowy przewodnik po stanie przesyłania formularza i śledzeniu postępu

Formularze stanowią podstawę niezliczonych aplikacji internetowych, służąc jako główny interfejs interakcji z użytkownikiem. Jednak zarządzanie przesyłaniem formularzy, obsługa błędów i dostarczanie informacji zwrotnej użytkownikom może być złożonym zadaniem. Hak useFormStatus w React upraszcza ten proces, oferując usprawniony sposób na śledzenie stanu przesyłania formularza i zapewnienie bardziej intuicyjnego doświadczenia użytkownika.

Czym jest `useFormStatus`?

Wprowadzony w React 18, useFormStatus to hak zaprojektowany w celu dostarczania informacji o stanie przesyłania elementu <form>. Pozwala określić, czy formularz jest aktualnie przesyłany, został pomyślnie przesłany, czy też napotkał błąd podczas przesyłania. Informacje te można wykorzystać do aktualizacji interfejsu użytkownika, wyłączania przycisków, wyświetlania wskaźników ładowania lub dostarczania komunikatów o błędach użytkownikowi.

Kluczowe korzyści z używania `useFormStatus`:

Uproszczone zarządzanie stanem formularza: Eliminuje potrzebę ręcznego zarządzania stanem przesyłania formularza, redukując powtarzalny kod.
Lepsze doświadczenie użytkownika: Zapewnia użytkownikom informacje zwrotne w czasie rzeczywistym podczas przesyłania formularza, poprawiając użyteczność.
Zwiększona dostępność: Umożliwia dostępne interakcje z formularzem poprzez wyłączanie jego elementów podczas przesyłania i dostarczanie czytelnych komunikatów o błędach.
Zoptymalizowana wydajność: Efektywnie śledzi stan przesyłania formularza, zapobiegając niepotrzebnym ponownym renderowaniom.

Jak działa `useFormStatus`

Hak useFormStatus jest używany wewnątrz komponentu React, który renderuje element <form>. Hak zwraca obiekt zawierający następujące właściwości:

pending: Wartość logiczna (boolean) wskazująca, czy formularz jest aktualnie przesyłany.
data: Dane zwrócone przez funkcję akcji formularza (w przypadku powodzenia).
method: Metoda HTTP użyta do przesłania formularza (np. "POST", "GET").
action: Funkcja, która została wywołana podczas przesyłania formularza.
error: Obiekt błędu, jeśli przesłanie formularza nie powiodło się.

Aby użyć useFormStatus, musisz najpierw zdefiniować funkcję action dla swojego formularza. Ta funkcja zostanie wywołana, gdy formularz zostanie przesłany. Wewnątrz funkcji action możesz wykonać dowolne niezbędne przetwarzanie danych, walidację lub wywołania API. Funkcja action powinna zwrócić wartość, która będzie dostępna we właściwości data haka useFormStatus. Jeśli akcja zgłosi błąd, ten błąd będzie dostępny we właściwości error.

Praktyczne przykłady użycia `useFormStatus`

Przykład 1: Podstawowe śledzenie przesyłania formularza

Ten przykład pokazuje, jak używać useFormStatus do śledzenia stanu przesyłania prostego formularza kontaktowego. Ten przykład działa w komponencie serwerowym React (RSC), co wymaga frameworka takiego jak Next.js lub Remix.


// app/contact/page.tsx (Next.js)
'use client';

import { useFormStatus } from 'react-dom';

async function submitForm(formData: FormData) {
  "use server";
  // Symulacja wywołania API
  await new Promise((resolve) => setTimeout(resolve, 2000));

  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name || !email || !message) {
    throw new Error('Proszę wypełnić wszystkie pola.');
  }

  console.log('Form Data:', { name, email, message });
  return { message: 'Formularz przesłany pomyślnie!' };
}

export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      Imię:
      


      Email:
      


      Wiadomość:
      


      

      {data && {data.message}}
      {error && Błąd: {error.message}}
    
  );
}

W tym przykładzie stan pending jest używany do wyłączania pól formularza i przycisku przesyłania na czas przesyłania formularza. Dynamicznie zmienia również tekst przycisku na "Przesyłanie...", aby zapewnić użytkownikowi wizualną informację zwrotną. W przypadku powodzenia wyświetlane są dane data z akcji submitForm. Jeśli podczas przesyłania wystąpi błąd, użytkownikowi wyświetlany jest komunikat o błędzie error.

Przykład 2: Wyświetlanie wskaźnika ładowania

Ten przykład pokazuje, jak wyświetlić wskaźnik ładowania podczas przesyłania formularza. Jest to szczególnie przydatne w przypadku formularzy, które obejmują długotrwałe wywołania API lub złożone przetwarzanie danych.


// Struktura komponentu podobna do Przykładu 1
export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      {/* ... pola formularza ... */}

      

      {pending && Ładowanie...} {/* Pokaż wskaźnik ładowania */}

      {data && {data.message}}
      {error && Błąd: {error.message}}
    
  );
}

W tym przykładzie prosty komunikat "Ładowanie..." jest wyświetlany, gdy stan pending jest prawdziwy. Możesz zastąpić go bardziej zaawansowanym wskaźnikiem ładowania, takim jak spinner lub pasek postępu.

Przykład 3: Obsługa błędów walidacji formularza

Ten przykład pokazuje, jak obsługiwać błędy walidacji formularza za pomocą useFormStatus. Funkcja action przeprowadza walidację i zgłasza błąd, jeśli którakolwiek z reguł walidacji zostanie naruszona.


// Struktura komponentu podobna do Przykładu 1
async function submitForm(formData: FormData) {
  "use server";
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name) {
    throw new Error('Imię jest wymagane.');
  }
  if (!email) {
    throw new Error('Email jest wymagany.');
  }
  if (!message) {
    throw new Error('Wiadomość jest wymagana.');
  }

  // Symulacja wywołania API
  await new Promise((resolve) => setTimeout(resolve, 2000));

  console.log('Form Data:', { name, email, message });
  return { message: 'Formularz przesłany pomyślnie!' };
}

export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      {/* ... pola formularza ... */}

      

      {error && Błąd: {error.message}} {/* Wyświetl komunikat o błędzie */}
    
  );
}

W tym przykładzie funkcja action sprawdza, czy pola imienia, e-maila i wiadomości są puste. Jeśli którekolwiek z tych pól jest puste, zgłasza błąd z odpowiednim komunikatem. Właściwość error haka useFormStatus jest następnie używana do wyświetlenia komunikatu o błędzie użytkownikowi.

Zaawansowane przypadki użycia i uwagi

Integracja z bibliotekami formularzy firm trzecich

Chociaż useFormStatus dostarcza natywne rozwiązanie do śledzenia stanu przesyłania formularza, można go również zintegrować z bibliotekami formularzy firm trzecich, takimi jak Formik czy React Hook Form. Biblioteki te oferują bardziej zaawansowane funkcje, takie jak walidacja formularzy, zarządzanie polami i zarządzanie stanem. Łącząc useFormStatus z tymi bibliotekami, można tworzyć wysoce konfigurowalne i solidne formularze.

Aby zintegrować się z Formik lub React Hook Form, można wykorzystać ich odpowiednie mechanizmy obsługi przesyłania formularzy i użyć useFormStatus do śledzenia ogólnego stanu przesyłania. Prawdopodobnie nadal trzeba będzie utworzyć Akcję Serwerową (Server Action), ale zarządzanie stanem formularza po stronie klienta byłoby obsługiwane przez wybraną bibliotekę.

Obsługa operacji asynchronicznych

Wiele formularzy obejmuje operacje asynchroniczne, takie jak wywołania API lub zapytania do bazy danych. W przypadku operacji asynchronicznych ważne jest, aby upewnić się, że przesyłanie formularza jest obsługiwane poprawnie i że użytkownik otrzymuje odpowiednią informację zwrotną. Hak useFormStatus upraszcza ten proces, dostarczając stan pending, który można wykorzystać do wskazania, że formularz oczekuje na zakończenie operacji asynchronicznej.

Kluczowe jest również zaimplementowanie solidnej obsługi błędów, aby z gracją radzić sobie z wszelkimi błędami, które mogą wystąpić podczas operacji asynchronicznych. Właściwość error haka useFormStatus może być używana do wyświetlania komunikatów o błędach użytkownikowi.

Kwestie dostępności

Dostępność jest kluczowym aspektem tworzenia stron internetowych, a formularze nie są wyjątkiem. Podczas budowania formularzy ważne jest, aby zapewnić ich dostępność dla użytkowników z niepełnosprawnościami. Hak useFormStatus można wykorzystać do poprawy dostępności formularzy poprzez:

Wyłączanie elementów formularza podczas przesyłania: Zapobiega to przypadkowemu wielokrotnemu przesłaniu formularza przez użytkowników.
Dostarczanie jasnych komunikatów o błędach: Komunikaty o błędach powinny być zwięzłe, informacyjne i łatwe do zrozumienia. Powinny być również powiązane z odpowiednimi polami formularza za pomocą atrybutów ARIA.
Używanie atrybutów ARIA: Atrybuty ARIA mogą być używane do dostarczania dodatkowych informacji o formularzu i jego elementach technologiom wspomagającym. Na przykład atrybut aria-describedby może być użyty do powiązania komunikatów o błędach z polami formularza.

Optymalizacja wydajności

Chociaż useFormStatus jest ogólnie wydajny, ważne jest, aby wziąć pod uwagę implikacje wydajnościowe podczas budowania złożonych formularzy. Unikaj wykonywania kosztownych obliczeń lub wywołań API wewnątrz komponentu, który używa useFormStatus. Zamiast tego, deleguj te zadania do funkcji action.

Bądź również świadomy niepotrzebnych ponownych renderowań. Używaj technik memoizacji w React (np. React.memo, useMemo, useCallback), aby zapobiec ponownemu renderowaniu komponentów, chyba że ich właściwości (props) uległy zmianie.

Dobre praktyki dotyczące używania `useFormStatus`

Utrzymuj swoje funkcje action zwięzłe i skoncentrowane: Funkcja action powinna głównie obsługiwać przetwarzanie danych, walidację i wywołania API. Unikaj wykonywania złożonych aktualizacji interfejsu użytkownika lub innych efektów ubocznych wewnątrz funkcji action.
Dostarczaj użytkownikom jasne i informacyjne informacje zwrotne: Używaj właściwości pending, data i error haka useFormStatus, aby dostarczać użytkownikom informacje zwrotne w czasie rzeczywistym podczas przesyłania formularza.
Wdrażaj solidną obsługę błędów: Z gracją obsługuj wszelkie błędy, które mogą wystąpić podczas przesyłania formularza, i dostarczaj użytkownikowi informacyjne komunikaty o błędach.
Bierz pod uwagę dostępność: Upewnij się, że Twoje formularze są dostępne dla użytkowników z niepełnosprawnościami, stosując najlepsze praktyki w zakresie dostępności.
Optymalizuj wydajność: Unikaj niepotrzebnych ponownych renderowań i kosztownych obliczeń wewnątrz komponentu, który używa useFormStatus.

Zastosowania w świecie rzeczywistym i przykłady z całego świata

Hak useFormStatus może być stosowany w różnych scenariuszach opartych na formularzach w różnych branżach i lokalizacjach geograficznych. Oto kilka przykładów:

E-commerce (Globalnie): Sklep internetowy może używać useFormStatus do śledzenia przesyłania formularzy zamówień. Stan pending może być użyty do wyłączenia przycisku "Złóż zamówienie" podczas przetwarzania zamówienia, a stan error do wyświetlania komunikatów o błędach, jeśli zamówienie nie zostanie przesłane (np. z powodu problemów z płatnością lub braków w magazynie).
Opieka zdrowotna (Europa): Dostawca usług medycznych może używać useFormStatus do śledzenia przesyłania formularzy rejestracji pacjentów. Stan pending może być użyty do wyświetlania wskaźnika ładowania podczas przetwarzania informacji o pacjencie, a stan data do wyświetlenia komunikatu potwierdzającego po pomyślnej rejestracji. Zgodność z RODO (Ogólne Rozporządzenie o Ochronie Danych) jest najważniejsza, a komunikaty o błędach związane z naruszeniami prywatności danych muszą być obsługiwane z należytą starannością.
Edukacja (Azja): Platforma e-learningowa może używać useFormStatus do śledzenia przesyłania zadań. Stan pending może być użyty do wyłączenia przycisku "Prześlij" podczas przesyłania zadania, a stan error do wyświetlania komunikatów o błędach, jeśli przesyłanie nie powiedzie się (np. z powodu ograniczeń rozmiaru pliku lub problemów z siecią). Różne kraje mogą mieć różne standardy akademickie i wymagania dotyczące przesyłania, które formularz musi uwzględniać.
Usługi finansowe (Ameryka Północna): Bank może używać useFormStatus do śledzenia przesyłania formularzy wniosków kredytowych. Stan pending może być użyty do wyświetlania wskaźnika ładowania podczas przetwarzania wniosku, a stan data do wyświetlenia statusu zatwierdzenia kredytu. Zgodność z przepisami finansowymi (np. KYC - Know Your Customer) jest kluczowa, a komunikaty o błędach związane z kwestiami zgodności muszą być jasne i konkretne.
Usługi rządowe (Ameryka Południowa): Agencja rządowa może używać useFormStatus do śledzenia przesyłania formularzy opinii obywatelskich. Stan pending może być użyty do wyłączenia przycisku "Prześlij" podczas przetwarzania opinii, a stan data do wyświetlenia komunikatu potwierdzającego po pomyślnym przesłaniu. Dostępność jest krytyczna, ponieważ obywatele mogą mieć różny poziom umiejętności cyfrowych i dostępu do technologii. Formularz musi być dostępny w wielu językach.

Rozwiązywanie typowych problemów

useFormStatus nie aktualizuje się: Upewnij się, że używasz React 18 lub nowszej wersji oraz że Twój formularz ma prawidłowo zdefiniowaną akcję action. Sprawdź, czy Twoja Akcja Serwerowa (Server Action) jest poprawnie zdefiniowana za pomocą dyrektywy "use server".
Komunikaty o błędach nie wyświetlają się: Sprawdź dokładnie, czy Twoja funkcja action prawidłowo zgłasza błędy i czy wyświetlasz error.message w swoim komponencie. Sprawdź konsolę pod kątem błędów podczas przesyłania formularza.
Formularz przesyła się wielokrotnie: Upewnij się, że przycisk przesyłania jest wyłączony za pomocą stanu pending, aby zapobiec przypadkowym podwójnym kliknięciom.

Wnioski

Hak useFormStatus w React zapewnia potężny i wygodny sposób na śledzenie stanu przesyłania formularza i zapewnienie lepszego doświadczenia użytkownika. Upraszczając zarządzanie stanem formularza, poprawiając dostępność i optymalizując wydajność, useFormStatus daje programistom możliwość tworzenia solidnych i przyjaznych dla użytkownika formularzy. By rozumiejąc jego możliwości i najlepsze praktyki, możesz wykorzystać useFormStatus do tworzenia płynnych i angażujących interakcji z formularzami w swoich aplikacjach React.